You have used all Bugbot PR reviews included in your free trial for your GitHub account on this workspace.

To continue using Bugbot reviews, enable Bugbot for your team in the Cursor dashboard.

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Mar 18, 2026 1:13am

Greptile Summary

This PR adds a knowledge_upsert_document tool and backing API route that replaces the manual delete-then-create workflow for updating knowledge base documents. The implementation is well-structured: it introduces a new POST route at /api/knowledge/[id]/documents/upsert, a typed tool definition following existing conventions, and extends the Knowledge block dropdown with the new operation.

All critical issues raised in the previous review thread have been resolved:

• Create-before-delete ordering prevents data loss if createDocumentRecords fails.
• firstDocument null guard is in place before accessing .documentId.
• Compensating rollback (deleteDocument(firstDocument.documentId)) executes if the old-document delete fails, preventing orphaned pending records.
• documentId vs filename lookup is now an if/else — a stale documentId no longer silently falls through to filename-based replacement.
• Zod validation runs before authorizeWorkflowByWorkspacePermission, so validatedData.workflowId (not raw body.workflowId) is used for auth.
• Byte-count size check and loop-based btoa fallback correctly handle multi-byte content.
• Duplicate sub-block IDs (name, content) in knowledge.ts were collapsed into single entries with array conditions.

One minor UX suggestion: the "Document ID (Optional)" sub-block currently appears after "Document Tags" in the form — reordering it before documentTags would better match the lookup-then-fill mental model users have when updating an existing document.

Confidence Score: 4/5

• This PR is safe to merge — all previously identified critical issues have been addressed and no new logic or security issues were found.
• The implementation is thorough: correct create-before-delete ordering, null guards, rollback on failure, validated inputs before auth, and consistent patterns with the existing create_document tool. The tool executor (utils.server.ts) confirms it checks response.ok before calling transformResponse, so the success: true pattern in the transform is safe. The only remaining item is a minor UX ordering suggestion for the upsertDocumentId sub-block in the block form.
• No files require special attention; the route and tool implementation are both sound.

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant Client as Tool Client
    participant Route as POST /api/knowledge/[id]/documents/upsert
    participant DB as Database
    participant DocSvc as Document Service

    Client->>Route: POST { filename, fileUrl, documentId?, ... }
    Route->>Route: checkSessionOrInternalAuth()
    Route->>Route: UpsertDocumentSchema.parse(body)
    Route->>Route: authorizeWorkflowByWorkspacePermission() (if workflowId)
    Route->>Route: checkKnowledgeBaseWriteAccess()

    alt documentId provided
        Route->>DB: SELECT id WHERE id=documentId AND knowledgeBaseId AND deletedAt IS NULL
        DB-->>Route: existingDoc (may be empty)
    else no documentId
        Route->>DB: SELECT id WHERE filename=filename AND knowledgeBaseId AND deletedAt IS NULL
        DB-->>Route: docsByFilename (may be empty)
    end

    Route->>DocSvc: createDocumentRecords([{filename, fileUrl, ...}])
    DocSvc-->>Route: createdDocuments[]

    Route->>Route: Guard: firstDocument = createdDocuments[0]

    alt existingDocumentId found
        Route->>DocSvc: deleteDocument(existingDocumentId)
        alt delete fails
            DocSvc-->>Route: throws
            Route->>DocSvc: deleteDocument(firstDocument.documentId) [rollback]
            Route-->>Client: 500 Failed to replace existing document
        end
    end

    Route->>DocSvc: processDocumentsWithQueue() [fire & forget]
    Route->>Route: recordAudit(DOCUMENT_UPDATED | DOCUMENT_UPLOADED)
    Route-->>Client: 200 { success, data: { documentsCreated, isUpdate, previousDocumentId } }

_{Last reviewed commit: "lint"}

@greptile

@greptile

@greptile

@greptile